PI: Dr. Thomas Girke, professor at Department of Botany and Plant Sciences, University of California, Riverside (thomas.girke@ucr.edu)
Maintainer: Jianhai Zhang (jzhan067@ucr.edu; zhang.jianhai@hotmail.com)
This spatialHeatmap package can be used for interactive visualisation as long as a data matrix and an associated SVG image are provided. This tutorial is specifically designed for how to make an SVG image and link it with gene expression matrix. The tutorial requires a png image with regions coloured by different colours, a data matrix, the SVG editor Inkscape, and optionally the image editor GIMP. The png image is the template to make the SVG image while the data matrix is used to fill different regions in the image. Inkscape is used to associate the SVG image with the data matrix and GIMP is optionally used to facilitate making the SVG image.
In the following, the tutorial is given with a gene expression matrix and an associated root tissue image in SVG format as an example, which is just a basic example for users to start. All the files used in this tutorial can be downloaded here (download an SVG image: click the image, right-click, select “Save image as…”; download a PNG image: click the image, click “Download”, right-click, select “Save image as…”; download a TXT file: click the file, click “Raw”, right-click, select “Save as…”.).
Users are advised to pay enough attention to the bold text below, because it can prevent common errors when creating the SVG images.
In the gene expression matrix, the row and column names are usually gene IDs and sample/conditions, respectively. The sample/condition names MUST be fomatted this way: a sample name is followed by double underscore then the condition, such as “stele__140mM_48h" (Mustroph et al. 2009), where stele is the sample and 140mM_48h is the condition. One column of meta data (e.g. gene annotation) can also be included in parallel with sample/condition at the end. In the column names of sample/condition and meta data, only letters, digits, single underscore, dots are allowed. Not all samples in the matrix necessarily need to be present in the svg image, and vice versa. Only samples present in the svg image are recognised and coloured. The example of partial gene expression matrix is shown below (Xie 2014; Zhu 2019; Dowle and Srinivasan 2018).
If the contour in the png image is not clear, GIMP can generate low-quality SVG images. In this case, one can draw the blank SVG image with Inkscape by using the png as a template. Below is an example of drawing only two polygons.
The drawing method produce accurate SVG images but it is time-consuming, while the GIMP method is faster but it can generate fused polygons. In this tutorial, the root png image has well separated polygons and clear contours, so GIMP can produce accurate SVG images. Otherwise the resulting SVG images would have mixed and noise polygons. Considering the pros and cons of two methods, the good practice is to use GIMP to extract polygons first then use drawing the refine the blank SVG image. Below is an example of an SVG image with fused polygons, which is generated by GIMP.
If a large fused polygon needs to be separated, one can use the eraser tool. Drag the fused polygon away from the tissue, select the eraser tool from the left tool bar, then use the eraser to cut the fused polygon into three independent polygons. Select the cut polygons and click “Break Apart” under the “Path” tab at the top, then the three polygons are entirely separated. Place back the three polygons to make the tissue complete.
In the SVG image, each polygon is defined by a string of coordinates, and these strings have unique IDs. To use the Spatial Heatmap, these IDs should be replaced with sample names exactly from gene matrix. No matter how the blank SVG image is created, it should be placed inside a layer before linked to the gene matrix .
Users can add text to label tissues. Basically, the text is first typed in with the text tool and then the text object is coverted to paths. Next text paths are added into the polygon group of target tissue and filled with the same tissue colour.
To add a pointer, draw a rectangle and convert it to path, fill it with the same style as the target tissue, then move, rotate and resize it.
Click one of any other tissues, then drag the target tissue to see the text and pointer are grouped together with the target.
The process of making SVG file is error-prone, if errors arise in the Spatial Heatmap app, such as some tissues are missing, then users are advised to double check the bold text above.
https://www.w3schools.com/graphics/svg_intro.asp
https://www.gimp.org/tutorials/
https://inkscape.org/en/doc/tutorials/advanced/tutorial-advanced.en.html
Dowle, Matt, and Arun Srinivasan. 2018. Data.table: Extension of ‘Data.frame‘. https://CRAN.R-project.org/package=data.table.
Mustroph, Angelika, M Eugenia Zanetti, Charles J H Jang, Hans E Holtan, Peter P Repetti, David W Galbraith, Thomas Girke, and Julia Bailey-Serres. 2009. “Profiling Translatomes of Discrete Cell Populations Resolves Altered Cellular Priorities During Hypoxia in Arabidopsis.” Proc Natl Acad Sci U S A 106 (44): 18843–8.
Xie, Yihui. 2014. “Knitr: A Comprehensive Tool for Reproducible Research in R.” In Implementing Reproducible Computational Research, edited by Victoria Stodden, Friedrich Leisch, and Roger D. Peng. Chapman; Hall/CRC. http://www.crcpress.com/product/isbn/9781466561595.
Zhu, Hao. 2019. KableExtra: Construct Complex Table with ’Kable’ and Pipe Syntax. https://CRAN.R-project.org/package=kableExtra.